Developer CD Series 1998 August: Tool Chest/Dev.CD Aug 98 TC.toast/Tool Chest/Development Kits/MPW etc./Debuggers/SADE/SADE 1.3.3/sade.help

Text File | 1992-06-12 | 100.1 KB | 2,888 lines | [TEXT/sade]

SADE 1.3 Help Summaries

    Help summaries are available for each of the SADE commands.
    To see the list of commands enter "Help Commands". In addition,
    brief descriptions of Variables, Constants, Expressions, built
    in functions, and Shortcuts are also included.

    To see Help summaries, Enter a command such as

    Help Builtins        # a list of builtin (predefined) variables and functions
    Help commandName    # information about commandName
    Help Commands        # a list of commands
    Help Expressions    # summary of expressions
    Help Patterns        # summary of patterns (regular expressions)
    Help Shortcuts        # summary of SADE shortcuts
    Help Variables         # summary of variable references
    Help Basetypes        # summary of basic types recognized by SADE

    Copyright Apple Computer, Inc. 1987-1992
    All rights reserved.

-
Builtins

    Functions
        AddrToSource    # tries to display source for a particular code address
        Concat             # concatenate strings
        Confirm            # confirmation dialog
        Copy             # extract a substring from a string
        Eval            # evaluate the contents of a string
        Find            # find pattern in memory
        Length             # length of a string
        NaN             # SANE NaN (Not a Number)
        Request            # request dialog returning string
        SizeOf             # size of a value or type
        SourceToAddr    # tries to give code address for a point in a source file
        Timer            # "tick count" timer with conversion to minutes,seconds,hundreths
        TypeOf             # type (name) of a value
        Undef             # is a value undefined?
        Where             # symbolic representation of an address

    Variables
        Arg[n]             # n'th parameter to current Proc or Func
        ActiveWindow    # string with pathname of topmost SADE window
        Date            # string with current date in the form dd-mmm-yy
        DisAsmFormat    # string controlling format of DisAsm command output
        Exception         # number of last exception raised
        Inf             # SANE infinity
        NArgs             # number of actual parameters to current Proc or Func
        ProcessId         # id of current process being debugged (an integer)
        TargetWindow    # string with pathname of the SADE window below the topmost one
        Time            # string with current time in the form hh:mm:ss
        WorksheetWindow    # string with pathname of SADE Worksheet window

-
Commands

    Abort            Execute            OnEntry                Stack
    AddMenu            Find            Open                Step
    Alert            For                Printf                Stop
    Beep            Func            Proc                Target
    Begin            Go                Quit                Trace
    Break            Heap            Redirect            Unbreak
    Case            Help            Repeat                Undefine
    Close            If                Resource            Untrace
    Cycle            Kill            Return                Version
    Define            Leave            SADEKey                While
    DeleteMenu        List            Save                WindowSize
    Directory        Loop            Shutdown
    Disasm            Macro            SizeWindow
    Dump            MoveWindow      SourcePath

Functions

    AddrToSource      Eval            Request          Timer
    Concat            Find            Selection        TypeOf
    Confirm           Length          SizeOf           Undef
    Copy              Nan             SourceToAddr     Where
-
Expressions

    The operators listed below are used in expressions in command
    parameters.

    (…)             grouping

    @                address of
    †                trap expression

    ^                pointer to
    .                variable reference qualifier

    -                unary negation
    ~                bitwise ones complement
    !     NOT  ¬     logical NOT (¬ is Option-L)

    *                multiplication
    /     DIV  ÷        division (÷ is Option-/)
    //     MOD        remainder

    +                addition
    -                subtraction

    <<                shift left
    >>                shift right

    =     ==            equal
    <>   !=      ≠     not equal (≠ is Option-=)
    <                less than
    <=     ≤            less than or equal (≤ is Option-<)
    >                greater than
    >=     ≥            greater than or equal (≥ is Option->)

    &     AND        bitwise AND
    &&                logical AND

    XOR     EOR        bitwise exclusive OR
    |     OR            bitwise OR
    ||                logical OR

    :=                size compatible assignment
    <-                arbitrary assignment

    Alternate spellings of several operators are provided.
    All of the operators are evaluated from left to right.
    Operators with the highest precedence are listed first,
    and operators in the same group have equal precedence.

-
Patterns - Patterns specify characters to be matched.  Patterns may only be
           used from the Find… command in the Find menu.

    /entireRE/                regular expression - search forward
    \entireRE\                regular expression - search backward

entireRE

    •RE                     regular expression at beginning of line (Option-8)
    RE∞                     regular expression at end of line (Option-5)
    RE                        regular expression

RE

    simpleExpr                simple regular expression - defined below
    'string'                literal - no characters within '…' are special
    "string"                literal - only \, ∂, {, and ` are special within '…'
    RE1RE2                    regular expression RE1 followed by RE2

simpleExpr

    (RE)                    regular expression grouping
    charExpr                single character regular expression - defined below
    simpleExpr*             simple expression zero or more times
    simpleExpr+             simple expression one of more times
    simpleExpr«n»            simple expression n times (Option-\, Option-Shift-\)
    simpleExpr«n,»            simple expression at least n times
    simpleExpr«n1,n2»        simple expression at least n1, at most n2 times

charExpr

    character                character (unless it has special meaning)
    ∂character                character - defeats any special meaning (Option-D)
    ?                        any character except Return
    ≈                        zero or more characters, except Return (Option-X)
    [charList]                any character in the list
    [¬charList]             any character not in the list (Option-L)

charList

    ]                        ] first in the list represents itself
    -                        - first in the list represents itself
    character                character
    charList character        list of characters
    character-character     character range (e.g. A-Z)

-
ShortCuts
    The following is a list of SADE shortcuts:

    Double click        select word
    Triple click        select line
    Double clicking before any quote (', ", or `) will select until
        the matching quote
    Double clicking before or after {}[]() will select until
        the matching character

    UpArrow             move selection point one line above current selection
    DownArrow           move selection point one line below current selection
    RightArrow          move selection point one character to the right
    LeftArrow           move selection point one character to the left


    CMD-Shift-UpArrow    select text from current selection point to top of screen
    CMD-Shift-DownArrow    select text from current selection point to bottom of screen


    CMD-Opt-UpArrow       move selection point to top of file
    CMD-Opt-DownArrow     move selection point to bottom of file
    CMD-DownArrow       move selection point down to bottom of screen
    CMD-RightArrow      move selection point to right edge of current line
    CMD-UpArrow         move selection point to top of screen
    CMD-LeftArrow       move selection point to left edge of current line
    CMD-Backspace       delete from current selection to end of file

    In Dialogs without an Edittext item
        Y               Yes
        N               No
        CMD .           Cancel

-
Variables
    VARIABLE REFERENCES

    There are three different types of variables -- program variables, debugger
    variables, and system variables.  Program variables are defined in your
    program; debugger variables are defined during your debugging session; and
    system variables represent objects in the Macintosh runtime environment
    (e.g., registers, low-memory globals, and ROM locations).

    When SADE looks up a simple symbol name, it is first looked up as a debugger
    symbol, then as a program symbol, and finally as a system symbol.  Thus, if
    the same name is used as a debugger symbol and as a program symbol the
    debugger symbol will be returned.  In order to resolve such potential name
    conflicts SADE supports two escape characters, which may preceed an
    identifier to indicate whether the identifier is a program or system symbol:

        ` (backquote) identifies a symbol as a program symbol
        Δ (option j)  identifies a symbol as a system symbol

    PROGRAM VARIABLES

    The simplest form of program variable reference is just the name of the
    variable itself.  A simple reference (a single identifier) is looked up
    in the current name scope (CNS) as defined by where execution has stopped
    in the program.  If execution has stopped in a particular procedure, then
    the variables of that procedure and the global variables in the compilation
    unit of that procedure will be accessible via simple references.

    If you need to reference a variable which is outside of the current name
    scope (i.e., not in the procedure where execution has been suspended or
    not one of the globals in the compilation unit of that procedure) then a
    fully qualified reference is needed.  A fully qualified reference is very
    much like a complete file pathname describing how to get to the variable
    from a particular compilation unit.  The syntax is:

        \unit [.procedure]* .variable

    where \ indicates that a unit name follows.  In Pascal this will be the name
    on the UNIT or PROGRAM statement; in C or assembly this will be the name of
    the compilation unit's file (with ∂'s used to escape any characters not
    normally allowed in identifiers).  The [.procedure]* indicates zero or
    more procedure names (more than one for nested procedures) separated by dots.
    This will identify the path to a variable when it is not in the current CNS.

    DEBUGGER VARIABLES

    Debugger variables are defined with the DEFINE command.  These variables
    can be used to save values from the user program, to control debugger
    language contructs, etc.  Debugger variables are untyped, that is, they
    take on the type of the value that is assigned to them (which may change
    the next time they are assigned to).  The format of the define command is:

        Define [global] {declaration [':=' initialization]},…

    where
          "declaration" is a variable name followed by an optional dimension
            specification in square brackets, and
        "initialization" is a simple expression in the case of a scalar
            variable, or, an parenthesized list of expressions (separated by
            commas) in the case of an array variable.  A list of values for
            an array may include items of the form "n of v" where "n" is
            an expression specifying a count and "v" is an expression specifying
            a particular value.

    Any number of variables may be declared in a single DEFINE command.  The
    DEFINE command is not allowed inside of conditional or looping constructs.

    Arrays/Scalars:
        Scalar variables hold a value of any type.  An array variable will hold
        up to its specified dimension of values of any type; these values may
        be heterogeneous, that is, they need not be of the same type.

    Scope:
        Variables which are defined outside of PROCs or FUNCs are global, and
        are accessible both inside and outside of PROCs.  Variables which are
        defined inside of PROCs and FUNCs are local and have a lifetime limited
        to the particular activation of the PROC or FUNC, unless the optional
        "global" keyword was specified in the DEFINE command.

-
Basetypes

    The following basic types are recognized by SADE.  They are grouped in
    order of increasing size or related category:

    Boolean            # 1 byte Pascal boolean (bit 0 = 0 ==> false; 1 ==> true)
    UnsignedByte    # Unsigned byte
    Byte            # Signed byte
    Cchar            # Character byte

    UnsignedWord    # Unsigned word (2 bytes)
    UnsignedShort    # Same as UnsignedWord
    Word            # Signed word
    Short            # Same as Word
    Integer            # Same as Word
    Pchar            # Pascal character word (low byte contains character)
    PascalChar        # Same a Pchar

    UnsignedLong    # Unsigned long (4 bytes)
    UnsignedInt        # Same as UnsignedLong
    Long            # Signed long
    Int                # Same as long
    LongInt            # Same as Long

    PString            # Pascal variable length string
    CString            # C null-terminated string
    AsIsString        # As-is string (Packed array of char)

    Real            # Floating point single precision (4 bytes)
    Float            # Same as Real
    Single            # Same as Single
    Double            # Floating point double precision (8 bytes)
    Extended        # Floating point extended precision (10 bytes)
    Extended12        # MC68881 floating point extended precision (12 bytes)
    Comp[utational]    # Floating point computational integer (8 bytes)
-
Abort —stops execution of scripts
 Syntax
     Abort

 Description
    The Abort command terminates execution of the current script and
 returns you to SADE, canceling all pending commands. This means that if current
 execution is within a structured statement (Begin...End, for instance), or if multiple
 commands are selected, these pending commands are not executed. To terminate a break
 action without canceling pending commands, use the Stop command.

 Example

    The way in which  keyDown and mouseDown events are handled by the EventFilter
 procedure in this example illustrates the difference between Abort and Stop. A
 keyDown event (in the context of this example) does not entail any additional action,
 so you can use Abort to terminate the break action and return to SADE immediately. In
 the case of a mouseDown event, however, the location of the mouse when the break
 occurs is important; therefore, you use Stop to terminate the break action so that the
 Printf command showing the location of the mouse is executed before SADE is
 reentered.


 #-- Establish target, suspending application
 #-- and reentering SADE at main.(1)

 Directory 'VolName:some:path:toProg:'
 Target 'MyProg'
 Break \MyProg.main.(1)

 #-- Break action examines the current event type
 #-- (assuming the event record is named myEvent).
 #-- For mouseDown, shows coordinates of mouseDown and stops
 #-- (quitting break action but executing rest of pending SADE commands)
 #-- For keyDown, aborts (quitting break action AND rest of commands).
 #-- For any other event, shows event type and continues executing
 #-- (by default, break actions end with an implicit Go command)

 Proc EventFilter
    Define global mouseAt;
    If myEvent.what = 1 then    # mouseDown event
        mouseAt := myEvent.Where;
    Stop;
    elseif myEvent.what = 3 # keyDown event
        "keyDown"; Abort;
    else
        Printf "Event type %d: \n", myEvent.what;
        Printf;
    End
 End

 Begin
    Break _getNextEvent from applzone..applzone^ EventFilter
    Go
    Printf "Mouse down at H: %d\n          V: %d\n", mouseAt.h, mouseAt.v;
 End

 #-- output
 Event type 0:
 Event type 8:
 Event type 6:
 Mouse down at H: 208
               V: 144

 #-- With same break action in place, restart target.
 Go

 #-- output
 Event type 6:
 keyDown

 See also    Break, Stop
-
AddMenu —creates a menu or adds menu items
 Syntax
     AddMenu [ menuName  [ itemName  [ command  ] ] ]

 Description
    The AddMenu command lets you create menus and add menu items to
 execute SADE commands. The parameters menuName, itemName, and command
 are all string expressions; if they are string constants, you must enclose them in
 quotation marks.

    If a menu of menuName does not exist in the menu bar, a new menu is created. If a
 menu item with the specified itemName already exists, it is replaced; otherwise, a new
 menu item is created. You can include a keyboard equivalent for the item by listing
 the key after a slash (/) at the end of the string. See the “Examples” section.
 (Warning: Be careful not to inadvertently specify a keyboard equivalent that is
 already defined for a different menu item, because the new definition will replace the
 existing one without any warning.)
    The command specifies a string that is executed when a user clicks on itemName.
 It can be a SADE command (see the first example), or something more complex,
 such as the name of a procedure that you have defined (see the second example).
    If you do not specify itemName or command, AddMenu returns the current value
 from the specified level down. For instance, if you specify itemName without any
 commands, AddMenu displays the command that’s currently defined for that menu
 item. If you omit menuName, itemName, and commandName as well, SADE returns
 the current values for all user-defined menus and menu items.

 Example 1

 #-- Create a menu called Debug with two items, Disasm and Code
 #-- Disasm disassembles instructions starting at the end of the last
 #-- disassembly. Code Resources displays information about code resources.
 #-- Note that you can invoke Disasm from the keyboard with Command-4.

 AddMenu 'Debug' 'Disasm/4' 'Disasm'
 AddMenu 'Debug' 'Code Resources' 'Heap restype "CODE"'

 Example 2

 #-- Define a procedure called ShowWhere and then create a menu item,
 #-- Statement Selected Is?, which executes this procedure. ShowWhere shows what
 #-- routine a selected statement belongs to; if there isn't sufficient symbol
 #-- information, ShowWhere displays an error message explaining why it cannot
 #-- show the routine name.

 Proc ShowWhere
    Define loc := SourceToAddr(ActiveWindow, 1)
    If typeOf(loc) = 'PString' then
        Alert Concat('Cannot determine address from source: ', loc)
    else
        Alert Concat('At ', Where(loc))
    End
 End

 AddMenu 'SourceCmds' 'Statement Selected Is?' 'ShowWhere'

 See also    DeleteMenu
-
AddrToSource —displays source statement corresponding to address
 Syntax
    AddrToSource (address [, Boolean ] )

 Description
    AddrToSource displays and selects the source statement corresponding
 to the specified address. If the source file isn’t already open, it is displayed as
 a read-only window. If the source file is already open as a read/write window,
 AddrToSource changes the window to read-only.
    If you omit the optional Boolean value or specify 0 (FALSE), SADE displays
 the source window behind the front most window (most likely the window from which
 you executed AddrToSource). If you specify a nonzero value for Boolean (TRUE), SADE
 brings up the window as the front most window.
    AddrToSource returns a Boolean value indicating whether it was able to display the
 source statement (TRUE) or not (FALSE).

 See also    SourceToAddr
-
Alert —displays an alert box

 Syntax
     Alert [ Beep ] message

 Description
    The Alert command displays an alert box containing the specified
 message. The alert box is displayed until you click the OK button. Message is
 a string expression; if it is a string constant, it must be enclosed in quotation
 marks. If beep is specified, a sound is generated when the alert box appears.

 Example

 If length(str) > 64 then
    Alert "string longer than expected"
 End

 See also    Beep
-
Beep —generates tones
 Syntax
     Beep [ note [,duration [,level ] ] ... ]

 Description
    The Beep command produces each given note for the specified duration and
 sound level. You must separate each note specification (that is each note and
 its optional duration and level) from the next note by blank spaces or tabs.
 If you do not specify note, SADE produces a standard Macintosh warning beep of
 predetermined pitch and duration.

     Note can be one of the following:
    •    A number indicating the count field for the square wave generator, as
        described in the Sound Driver chapter of Inside Macintosh, Volume II
    •    A string in the format [n ] letter [ # | b ], where n is an optional number
        indicating the octaves below or above middle C, followed by a letter
        indicating the note (A–G) and an optional sharp (#) or flat (b) character.

    Duration is specified in sixtieths of a second. The default duration
    is 15 (one-quarter second).

    Level specifies the magnitude of the sound. Your parameter can be a number
    from 0 to 255. The default level is 128.

 Example

 Beep '2C,20,75 2C#,40,150 -1D,60,75'

 #-- Play the three notes specified: C, C sharp, and D, for one-third,
 #-- two-thirds, and one full second, respectively. The middle note is
 #-- twice as loud as the other notes. C and C sharp are two octaves
 #-- above middle C. D is one octave below.

 See also    Alert
-
Begin ...End —groups commands
 Syntax
     Begin
        commands
    End

 Description
     The Begin...End construct allows you to group together or bracket a
 sequence of commands. You can use this construct to specify a break action
 consisting of multiple commands or procedure calls.

 Example 1

 #-- This example specifies a conditional break action that depends on the
 #-- value of the pointer theStr^.

 Break DisplayString.(4) Begin
    str := theStr^   # save value of parameter in variable str
    If str = '***' then
        Stop
    End
 End

 Example 2

 #-- This example shows how to use the Begin…End construct to nest Step commands.

 Step onEntry Begin
    Printf "gStopped is %d\n",gStopped
    Printf "newStopped is %d\n",newStopped
    Step onEntry Begin
        Printf "gStopped is %d\n",gStopped
        Printf "newStopped is %d\n",newStopped
    End
 End
-
Break —sets breakpoints
 Syntax
     Break addr ,... [ breakAction ]
        or
    Break  trap [ from addrRange ] ,... [ breakAction ]
        or
    Break  trapRange [ from addrRange ] ,... [ breakAction ]
        or
    Break all traps  [ from addrRange ] [ breakAction ]

Description
     The Break command sets one or more breakpoints in a target program’s
 code. There are two types of breakpoints: address breakpoints and trap breakpoints.
 You can follow either kind of breakpoint by a break action, that is, a command (or
 series of commands) that is executed when the breakpoint is reached.
    Addr specifies a RAM address or symbolic reference. If you use a symbolic
 reference, the code need not be in memory when you set the breakpoint.
    Trap specifies a trap name or number. You must prefix a trap number with the
 trap character (†, or Option-T) and a trap name with an underscore character
 (_InitGraf, for example).
    TrapRange specifies a range of traps. You must use the range operator (..)
 between trap names or numbers.
    BreakAction    Specifies a command or series of commands that is executed
 when the breakpoint is reached.
    From addrRange indicates that a break is to occur only when the trap is
 called from the specified range.
    All traps sets a breakpoint on every trap.
    You can set trap breakpoints on a single trap, a range of traps, or on all traps.
 In each case you can also specify a memory range so that  SADE breaks only when the
 trap is called from the specified range.
    If you want to specify the same trap in multiple Break commands, use the List
 command to see what breakpoints have been set. When implementing trap
 breakpoints, SADE first looks for a Toolbox or Operating System call that matches a
 specified trap name, checking the address range if one was given. If no match is
 found, SADE then looks for trap ranges containing the trap. SADE takes the most
 recently defined range containing the trap, again checking the address range if one
 was specified.

     Note: If you set an address breakpoint on a trap call for which a trap breakpoint
 has already been set, the address breakpoint is recognized and the trap breakpoint
 is not.

    If you have specified a break action, SADE resumes program execution after
 executing your break-action commands. There are two ways to suspend program
 execution as part of a break action. The Abort command returns control to SADE
 immediately, canceling any pending commands. The Stop command executes any
 pending commands and then returns control to SADE.

    Warning: SADE saves the commands you specify in the break action and
 does not interpret them until reaching the breakpoint. Symbol references that may
 appear to be correct when you define the break action may be out of scope when the
 action is actually executed. So make sure that program symbol references are
 correctly interpreted at the time the breakpoint is reached.

    Do not delete the breakpoint as part of a break action. SADE stores the break
 action with the breakpoint; if you remove the breakpoint, you throw away the
 break action as well — even though SADE is in the middle of executing it — so the
 action does not execute properly.

    Note: If no break action is specified and the execution command (Go, for
 instance) just prior to hitting a breakpoint is part of a structured statement
 (such as While...End), or if multiple commands were selected, the remaining commands
 are executed after hitting the breakpoint and re-entering SADE.

    You can specify multiple breakpoints, separated by commas, with a single
 Break command. If this command includes a break action at the end, the action is
 applied to all breaks in the list.

 Examples

 #-- This example shows breaks set on different traps, trap ranges, and traps called
 #-- from particular memory ranges.

 Break _GetResource
 Break †$A997..†$A9A0
 Break all traps from myproc.(1)..myproc.(5)
 Break all traps from applZone..applZone^

 #-- The following example sets multiple breakpoints.

 Break procB.(1), _LineTo from procA.(1)..procA.(1000), _setPort Begin; "hit one"; end

 List break
  procB.(1)   # $586398  # processID =5  # has break action
  _LineTo  # processID =5  # †$A891  # called from procA.(1) .. procA.(83)  # has break action
  _SetPort  # processID =5  # †$A873  # has break action

 #-- A break set on top of a matching breakpoint replaces the older one. Breakpoints match
 #-- if they are set on the same address or trap and the called from address range, if there
 #-- is one, matches.

Break DoMenuCommand.(0)
Break _LineTo

List Break
Trap _SetPort (†$A873)
Trap _LineTo (†$A891)
DoMenuCommand.(0)

See also    Abort, List, Stop, Trace, Unbreak
-
Case —changes case sensitivity
 Syntax
     Case on | off

 Description
     This command turns case sensitivity on and off. By default, case
 sensitivity is on, which means that when looking up symbols, SADE first performs a
 case-sensitive lookup. If the symbol isn’t found, SADE converts all the characters to
 uppercase and looks again. When case sensitivity is off, SADE converts all symbols to
 uppercase before any lookup, speeding up the search process.
    Because symbols in C are case sensitive, C programmers must have case sensitivity
 turned on or SADE will not recognize any of the symbols in the program (except those
 that are all uppercase). Pascal programmers, however, may want to set case sensitivity
 off to speed up performance. Note however, that even with case set to on, SADE will
 find Pascal symbols (no matter what combination of uppercase and lowercase
 characters you enter) because if SADE cannot find a symbol in a case-sensitive
 search, it performs a second search after converting all characters to uppercase.

 Examples

 #-- These examples illustrate how Case on and Case off work by showing
 #-- the output you get when typing symbols in different combinations of lowercase and
 #-- uppercase letters.


 #-- C programmers
 Case on

 CFunction

 #-- output
 CFunction.(0)

 CFUNCTION

 #-- output
 ### Could not find "CFUNCTION" as a program symbol

 cfunction

 #-- output
 ### Could not find "cfunction" as a program symbol

 Case off

 CFunction

 #-- output
 ### Could not find "CFunction" as a program symbol


 #-- Pascal programmers
 Case on

 PascalProc

 #-- output
 PASCALPROC.(0)

 PASCALPROC

 #-- output
 PASCALPROC.(0)

 Case off

 PascalProc

 #-- output
 PASCALPROC.(0)
-
Close —closes a file
 Syntax
     Close [ all | windowName ]

 Description
     The Close command closes the specified file or all files. WindowName is the name
 of the window (file) to close. It is a string expression and you must enclose it
 in quotation marks if it’s a string constant. Specifying all closes all of the open
 windows open in SADE.
    If you don’t specify any parameters, Close closes the target window. Note,
 however, that the SADE Worksheet file cannot be closed. If the contents of a file have
 not been saved, a dialog box asks whether they should be.

 Examples

 Close 'myFile'
 Close targetWindow   #no quotes needed--uses SADE variable targetWindow
-
Concat —concatenates strings
 Syntax
     Concat ( [ string,…] )

 Description
     Concat returns the concatenation of the specified string expressions. If
 you supply nonstring arguments, Concat tries to coerce them to strings. If you
 specify no arguments, Concat returns a null string.

 Example

 pathName := 'root:examples:'
 fileName := 'sample.c'
 Open Concat(pathName,fileName)        # equivalent to open 'root:examples:sample.c'
-
Confirm —displays confirmation dialog box
 Syntax
     Confirm ( message [, Boolean ] )

 Description
    Confirm presents a dialog box containing the specified message and
 either two or three buttons depending on the value you specify for Boolean. Confirm
 returns a number indicating the button that you press in the dialog box.
    If you omit the optional Boolean or specify 0, Confirm presents OK and Cancel
 buttons, and returns 1 or 0 respectively when you press them. If you specify a
 nonzero value for Boolean, Confirm presents Yes, No, and Cancel buttons, which
 return 1, 0, and –1 respectively when you press them.

 Example

 confirm('Are you sure?',1)

 See also    Request
-
Copy —copies string
 Syntax
     Copy ( string, characterIndex, length )

 Description
     Copy returns all or part of the specified string. Use characterIndex to indicate
 the first character to copy; for example, to start with the third character of the
 string, specify 3 (it’s 1-based). Use length to specify he length of the output
 string.

 Example

 #-- Strips the hard drive name off the directory path (because the
 #-- copy begins with the fifth character) and copies the rest of the
 #-- directory path to the pathName variable. You can then open a file
 #-- by concatenating pathName with a filename. This example specifies 255
 #-- as a number for the length because it is large enough to accommodate
 #-- long pathnames.

 directoryPath := 'root:examples:cexamples:'
 pathName := copy(directoryPath,5,255)
 Open Concat(pathName,'sample.c')
-
Cycle —continues execution within construct
 Syntax
     Cycle  [ if  Boolean ]

 Description
     The Cycle command causes execution to continue from the conditional test
 of a While, Repeat, or For construct, or from the beginning of a Loop construct.
 If a Boolean expression is specified, Cycle executes only if the Boolean
 expression (Boolean) evaluates to nonzero; otherwise execution continues immediately
 following the Cycle command.

 Example

 Define testNum := 0
 Define endNum := 6
 Define cycleMax := 4

 Repeat
    Printf "testNum = %d\n", testNum
    testNum := testNum + 1
    Cycle If testNum < cycleMax
    "\nDidn't cycle"
 Until testNum = endNum

 #-- output

 testNum = 0
 testNum = 1
 testNum = 2
 testNum = 3

 Didn't cycle
 testNum = 4

 Didn't cycle
 testNum = 5

 Didn't cycle

 See also    Leave
-
Define —declares a SADE variable
 Syntax
     Define [ global ] declaration [,...]
        where declaration has the form
    name [ [dimension] [ := initValue | = initValue  ] ]


 Description
     The Define command defines one or more SADE variables. You must define a variable
 before using it. The variable declaration identifies the name, scope, and
 (optionally) the initial value of the variable. Separate multiple declarations by
 commas. The name of the variable must be unique in the current scope unless
 you declare it global. The dimension is the size of the array if it is a structured
 variable. It is an expression enclosed in brackets. The initValue is an expression
 for the initial value of simple types, or for structured types a list of the
 following form:

    ( [ expr of ] initValue , ..)

 where the optional of clause allows for replication of a value.
    SADE variables are dynamically typed; that is, their type is determined on
 assignment (and may be changed by new assignments). SADE variables defined as
 arrays require an index. SADE array variables may contain a heterogeneous set of
 values; that is, the elements may contain values of different types.
    An initial value for simple types may optionally be specified by an expr following
 the assignment operator (:=) or, in this case only, (=). If the declared item is an
 array, a list of initial values may be specified as the values of the array elements.
    The scope of a variable can be either global or local. If a variable is defined
 outside a procedure (or function), its scope is automatically global. In other words,
 it is known both inside and outside of any procedures. If a variable is declared
 inside a procedure, its scope is local unless you specify the global option. If a
 global and a local variable exist with the same name, the local symbol overrides
 the global symbol.
    Redefining global variables replaces the previous definition, with one exception:
 If the definition is within a procedure, and the new definition matches the
 existing definition, then the existing definition is retained. For example, when a
 global variable is defined within a procedure or function and is given an initial
 value, the initialization occurs only when the variable is actually created.
 Subsequent invocations of the procedure do not affect the current value of the global
 variable, and can make use of the value left in the variable by the preceding
 invocation.
    You cannot use the Define command within any structured statement. To remove a
 variable definition, use the Undefine command.

 Examples

 #-- Define a five element array, with the first four elements true and the last
 #-- element false.

 Define global test[5] := (4 of 1,0)

 #-- Define a 30 element array, with the first 29 elements true and the last
 #-- element false.

 Define arraysize := 30
 Define myArray[arraysize] := (arraysize-1 of 1,0)

 #-- In the next example, note that the definition of index in RotateLeftOneWCarry()
 #-- is local to that procedure; otherwise it would be attempting to redefine the
 #-- global index that's used as a For loop counter when RotateLeftOneWCarry()
 #-- is called.

 Proc RotateLeftOneWCarry()
    Define global SADEArray[4] := ("indexed by one", 2, 3.33, "fourth and last")
    Define index
    Define holder
    For index := 1 to 4 do
        If index = 1 then
            holder := SADEArray[index]
        else
            SADEArray[index-1] := SADEArray[index]
            If index = 4 then
                SADEArray[index] := holder
            End
        End
    End
 End

 Define index
 Define holder
 For index := 1 to 4 do
    RotateLeftOneWCarry()
    For holder := 1 to 4 do
        SADEArray[holder]
    End
    Printf "\n"
 End
 Undefine RotateLeftOneWCarry

 #-- output
 2
 3.33
 fourth and last
 indexed by one

 3.33
 fourth and last
 indexed by one
 2

 fourth and last
 indexed by one
 2
 3.33

 indexed by one
 2
 3.33
 fourth and last

 See also    Undefine
-
DeleteMenu —deletes menus or menu items
 Syntax
     Deletemenu [ menuName [ itemName ] ]

 Description
     The DeleteMenu command deletes menus and menu items. MenuName specifies the
 name of a user-defined bar menu. If you specify menuName but do not specify itemName,
 SADE deletes the entire menu. Because menuName is a string expression, you must
 enclose it in quotation marks if it is a string constant.
    ItemName is an item in the bar menu that you specified with menuName. It is a
 string expression and you must enclose it in quotation marks if it is a string
 constant.
    You cannot delete the standard SADE menus and menu items (the Apple, File, Edit,
 Find, Mark, and Window menus).

    Warning: If you omit both menuName and itemName, SADE deletes all user-defined
 menus, that is, the SourceCmds and Variables menus (which are defined by commands
 in the SADEStartup file) and any menus that you have added in the SADEUserStartup
 file. You can restore these menus by executing SADEStartup and SADEUserStartup.

 Example

 Deletemenu "Special" "Launchapp"

 See also    AddMenu
-
Directory —sets or writes the default directory
 Syntax
     Directory  [ directoryName ]

 Description
     The Directory command sets the default directory for all SADE file-oriented
 operations to the specified directory. If you don’t specify directoryName SADE
 displays the current default directory. DirectoryName follows the same conventions
 as MPW, that is, you can specify a full or partial pathname. It is a string
 expression and you must enclose it in quotation marks if it is a string constant.
    If a directory specification contains a colon but does not begin the with a colon,
 SADE reads it as a complete pathname.

 Examples

 #-- Change the current directory of HD:MPW to HD:MPW:Examples

 Directory 'Examples'

 #-- Change the current directory of HD:MPW to HD:MPW:Examples:CExamples.
 #-- You can still specify a partial pathname, but you must precede the directory
 #-- name with a colon.

 Directory ':Examples:CExamples'

 #-- Define a macro for your work directory

 Macro here "'HD:MPW:Example:CExample'"
 Directory here

 See also    Sourcepath
-
Disasm —disassembles code
 Syntax
     Disasm  [ addr  [ count ] ]
        or
    Disasm  [ addrRange ]

 Description
     The Disasm command disassembles instructions starting at the location specified
 by addr or addrRange . The default behavior when no address is specified is to begin
 disassembling at the end of the last disassembly. If the value of the program
 counter has changed since the last disassembly, the program counter (PC) is used as
 the default starting address. If no range or count is specified, the number of
 instructions (not lines) disassembled defaults to 20.
    AddrRange specifies the range of addresses for the disassembly. You specify a
 starting and ending address separated by the range operator (..). See “Examples”.
    Each line of the disassembly output is divided into three fields: the address of
 the instruction, the hexadecimal encoding for the instruction, and the assembly code
 (opcode, operand, and comment). You can modify the presence, order, and format of
 these fields by changing the value of the built-in variable DisAsmFormat. The
 disassembly output also correlates source statement numbers with the assembly code
 instructions (see the second example).

 Examples

 #-- Disassemble five instructions in standard format, starting at the fourth
 #-- statement of the AdjustMenus routine.

 Disasm $23B5EE 5

 #-- output

 AdjustMenus.(4)
    0023B5EE  2F0B            MOVE.L         A3,-(A7)
    0023B5F0  7004            MOVEQ          #$04,D0
    0023B5F2  3F00            MOVE.W         D0,-(A7)
    0023B5F4  A939            _EnableItem                        ; A939
    0023B5F6  6008            BRA.S          AdjustMenus.(6)        ; 0023B600

 #-- Disassemble the instructions between the first and fourth statements of the
 #-- AdjustMenus routine.

 Disasm AdjustMenus.(1)..AdjustMenus.(4)

 #--output

 AdjustMenus.(1)
    0023B5D2  598F            SUBQ.L        #$4,A7
    0023B5D4  A924            _FrontWindow                        ; A924
    0023B5D6  285F            MOVEA.L        (A7)+,A4
 AdjustMenus.(2)
    0023B5D8  598F            SUBQ.L         #$4,A7
    0023B5DA  3F3C 0081       MOVE.W        #$0081,-(A7)
    0023B5DE  A949            _GetMHandle                        ; A949
    0023B5E0  265F            MOVEA.L        (A7)+,A3
 AdjustMenus.(3)
    0023B5E2  2F0C            MOVE.L        A4,-(A7)
    0023B5E4  4EBA 02FC       JSR            IsDAWindow.(0)        ; 0023B8E2
    0023B5E8  4A00            TST.B            D0
    0023B5EA  588F            ADDQ.L        #$4,A7
    0023B5EC  670A            BEQ.S            AdjustMenus.(5)        ; 0023B5F8
 AdjustMenus.(4)
    0023B5EE  2F0B            MOVE.L        A3,-(A7)
    0023B5F0  7004            MOVEQ            #$04,D0
    0023B5F2  3F00            MOVE.W        D0,-(A7)
    0023B5F4  A939            _EnableItem                        ; A939

 See also    Dump
-
Dump —displays memory
 Syntax    Dump  [ byte | word | long ] [ addr  [ count ] ]
    or
 Dump  [ byte | word | long ]  [ addrRange ]

 Description
     The Dump command displays memory at the location specified by addr or addrRange.
 If no parameter is given, the memory starting at the program counter is displayed.
 The memory is displayed in hexadecimal and ASCII characters according to the
 specified format, which may be byte, word (two bytes), or long (four bytes). The
 default format is word.
    Count specifies the number of bytes to dump. The default, if you do not specify
 a count, is 16 bytes.
    AddrRange specifies the range of addresses for the dump. You specify a starting
 and ending address separated by the range operator (..). See “Examples”.
    Remember that to dump the value of a variable myVar, you must specify Dump
 @myVar (since Dump myVar would take myVar’s value and use it as an address).

 Examples

 #-- Dump 16 bytes (the default if no count is specified) from the A5 register.

 Dump byte A5

 #-- output

 $00146A8E 00 14 68 74 FF FF FF FF  00 00 00 00 00 00 00 00  ..ht........

 #-- Dump 40 bytes from the A5 register and group the output in words.

 Dump word A5 40

 #-- output

 $00146A8E 0014 6874 FFFF FFFF  0000 0000 0000 0000  ..ht............
 $00146A9E 000E 6C66 0000 FFFF  FFFF FFFF FFFF FFFF  ..lf............
 $00146AAE 0001 4EF9 000E 6E00                       ..N...n.



 #-- Dumps 40 bytes from the A5 register and group the output in long words.

 Dump long A5..A5+40

 #-- output

 $00146A8E 00146874 FFFFFFFF  00000000 00000000  ..ht............
 $00146A9E 000E6C66 0000FFFF  FFFFFFFF FFFFFFFF  ..lf............
 $00146AAE 00014EF9 000E6E00  00                 ..N...n..

 See also    Disasm
-
Eval —evaluates string as an expression
 Syntax
     Eval (text, [ message ] )

 Description
     Eval evaluates the text of a string argument as an expression. The function
 result can be any type, depending on what the expression evaluates to. You can
 optionally supply a message; if an error occurs, Eval returns this message as the
 function result. If you do not supply a message and an error occurs, Eval aborts
 and reports the error.

 Example

 #-- Pass the name of a program variable (menuId) to a variable in SADE (theVar).
 #-- SADE uses the Printf command to print the name of the variable and Printf
 #-- with Eval to print its value. If SADE cannot determine the value of the program
 #-- variable (for example, because it is out of scope), Printf prints ??? (the
 #-- message part of Eval).

 theVar := menuId
 Printf "%t = %t\n", theVar, Eval(Concat('`', theVar), '???')

 #-- Note that this example uses Concat with the backquote character (`) to treat
 #-- theVar as a program symbol. The code in this example is similar to code in the
 #-- SADEStartup file that implements the Show Value menu item.
-
Execute —executes commands in a file
 Syntax
     Execute filename

 Description
     The Execute command executes the commands and definitions contained in the
 specified file. The Execute command can’t be used within a structured statement.
 Filename is the name of the file to execute. It is a string expression and must
 be enclosed in quotation marks if it’s a string constant.

 Example

 #--In this example, the Redirect command creates a file to hold output from SADE.
 #-- Entering a string echoes the string. That output is redirected to the file,
 #-- becoming the file’s contents. Here the string is a comment and a SADE command
 #-- to execute the contents of the next file in the chain.

 Open 'exec1'
 Redirect 'exec1'

    '"\n executing exec1 now"'
    "execute 'exec2'"

    Open "exec2"
    Redirect 'exec2'
        "'now executing exec2'"
        "execute 'exec3'"

        Open "exec3"
        Redirect 'exec3'
            '"Done in exec3"'

 Redirect pop all
 Execute "exec1"

 Alert "Try a tile windows here\n∂
    Then look at the worksheet for output"

 #-- output

 executing exec1 now
 now executing exec2
 Done in exec3
-
Find —searches for a target
 Syntax
     Find [ count ] pattern [ ,n ] [ addrRange [ mask mask ] ]
        or
    Find [ count ] pattern [ ,n ]  [ addr [ count ] [ mask mask ] ]
        or
    Find [ same  [ addrRange ] | [ addr  [ count ] ] ]

 Description
     The Find command searches memory for a specified pattern, which can be either
 a numeric or string expression. If you specify the count keyword, Find tells you how
 many occurrences of the target it found. If you omit the count keyword, Find displays
 the address of the first occurrence of the pattern. You can use the n parameter to
 specify which occurrence of the pattern you want; for instance, if you specify
 3 for n, Find returns the address of the third occurrence of the pattern.
    If the keyword count is specified, Find returns the number of occurrences of the
 target string it has found. If you omit it, Find displays the address of the first
 occurrence of the target string. An integer n indicates which occurrence of the
 target pattern you want; for example, if you specify 3, SADE displays the address of
 the third occurrence of the pattern. Note that you must precede this number with a
 comma.
    AddrRange is the address range in which to limit the search. If you do not specify
 a range of addresses (or a starting address), the search range is the MultiFinder
 block containing the application’s heap and stack (in other words, all of the memory
 that belongs to the application).
    Addr is an address at which to begin the search. You can also specify count, the
 number of bytes to search beyond the specified address; otherwise the search goes
 from the starting address to the end of memory. If you do not specify a starting
 address or range of addresses, the search range is the MultiFinder block containing
 the application’s heap and stack (in other words, all of the memory that belongs to
 the application).
    The mask parameter (prefaces by the mask keyword) is an optional numeric or
 string expression that is logically ANDed with the contents of each memory location
 before the search comparison is done.
    The same keyword instructs Find to search for the next occurrence of the same
 target pattern as specified in the last Find command. You can optionally specify
 a different address range or starting address and number of bytes for the search.
 If you used the count keyword in the previous Find command, you cannot use same in
 the next one; if you do so, SADE returns a message that the pattern cannot be found.
    Important: Remember that expression values in SADE are long words by default;
 to specify another size, use typecasting, as shown below.

 Examples

 Dump $20 $40
 $00000020 0027 A002 0027 A00A  0040 1F52 0027 A012  .'...'...@.R.'..
 $00000030 0027 A01A 0027 A032  0040 113C 0027 A02A  .'...'.2.@.<.'.*
 $00000040 0040 113C 0040 113C  0040 113C 0040 113C  .@.<.@.<.@.<.@.<
 $00000050 0040 113C 0040 113C  0040 113C 0040 113C  .@.<.@.<.@.<.@.<

 #-- Search $40 bytes for the number of occurrences of the string, $113C,
 #-- starting at address $20. The string has been cast to word size; otherwise
 #-- the default search would be for a long word and nothing in the range
 #-- matches $0000113C. The search finds nine occurrences of the string.

 Find COUNT (word)$113C $20 $40
 9

 #-- Search the range $20 to $96 for the string $113C and display the address
 #-- of the first occurrence of this string. The search string has been typecast
 #-- to word size using C style casting.

 Find (word)$113C $20..$96
 $0000003A

 #-- Search $40 bytes beginning at address $20 for the string $113C and display
 #-- the address of the second occurrence of this string. The search string has
 #-- been typecast to word size using Pascal style casting.

 Find word($113C), 2 $20 $40
 $00000042

 #-- Search the range $20 to $96 for the string $0000113C and display the address
 #-- of the first occurrence of this string. A mask has been used

 Find $0000113C $20..$96 MASK $0000ffff
 $00000038

 #-- Find the same target string as the last example, except the memory
 #-- range has been changed.

 Find SAME $40..$50
 $00000040
-
For ...End —loops with a control variable
 Syntax
     For clause [ do ]
        commands
    End
        where clause may have one of the following forms:
    var := expr to expr
    var  := expr downto expr
    var := expr , ...

 Description
     The For...End construct provides looping with a control variable. The enclosed
 commands are executed until the control variable has taken on each successive
 value in the range expressed by clause.
    You must declare the control variable var before using it, and you cannot specify
 an array variable. For the clause expr to expr, the commands are executed and the
 control value (var) is incremented once for each integer value in the range. For the
 clause expr downto expr, the control value is decremented. The third clause is a
 list of expressions; the commands are executed until the control variable has taken
 on the value of each of the listed expressions.
    You can nest For...End constructs; you may also use them within other flow-
control constructs, as well as in break actions. The control variable may be modified
within the body of the loop (but cannot, of course, be shared between nested
constructs).

 Example

 Define var := 0
 Define outerLooper, syncopation
 For outerLooper := 3 downto 1 do
    "\n"
    For syncopation := "one","two","three", var
        Printf "%d -- " , outerLooper
        syncopation
        var := var + 1
    End
 End

 #-- output

 3 -- one
 3 -- two
 3 -- three
 3 -- 0

 2 -- one
 2 -- two
 2 -- three
 2 -- 4

 1 -- one
 1 -- two
 1 -- three
 1 -- 8
-
Func ...End —defines a SADE function
 Syntax
     Func  name  [ ( argName ,... ) ]
        commands
    End

 Description
     SADE functions are delimited by the Func...End construct. The last statement to
 be executed must be a Return command specifying a return value. The type of a
 function is not specified in the definition but rather takes on the type of the
 value returned. (Thus functions are not limited to returning results of a single
 type.)
    SADE functions use conventional calling notation, with the function name
 followed by a list of parameters enclosed by parentheses. Function parameters are
 handled in the same fashion as procedure parameters, and the predefined SADE
 variables Arg and NArgs may be used. (See the description of the Proc command for
 an example using these variables.)  User-defined functions may be called anywhere
 an expression is allowed.

 Example

 #-- This function factors a number and displays the total.

 Func fact(n)
    If n <= 1.0 then
        Return 1.0
    else
        Return n * fact(n-1)
    End
 End

 See also    Proc, Return
-
Go —resumes execution
 Syntax
     Go [ til addr ,...] [ onEntry commands ]

 Description
     The Go command resumes program execution at the current program counter.
    If you specify the keyword til, SADE sets a temporary breakpoint at the specified
 address(es). When the breakpoint is encountered, SADE is reentered and the breakpoint
 is removed. Note that if you specify multiple breakpoints with the keyword til, SADE
 removes all breakpoints when any of them is reached. If the address is in ROM, SADE
 informs you that it can’t set a breakpoint in ROM.
    Use onEntry to specify an action to occur when SADE is reentered following
 resumption of the program—for example, to display the value of a variable. If you do
 not use onEntry but execute the Go command as part of a group of commands (in a
 script file or highlighted in the Worksheet) SADE evaluates the other commands first
 before executing Go regardless of the order in which you place the commands in the
 script or in the Worksheet.
    Important: You cannot execute a Step command following Go in a script or as
 part of a highlighted group of commands unless you use the onEntry keyword. With
 onEntry you can tell SADE to execute a Step command after returning to SADE
 following the Go command. (See the last example.)

 Examples

 #-- The first example resumes operation of the program and breaks at
 #-- \OtherCompilationUnit.myProc.(1).

 Go til \OtherCompilationUnit.myProc.(1)


 #-- Assume that the program is suspended and a breakpoint has been set within the
 #-- procedure that initializes the values of the variables gstopped and newstopped.
 #-- The following code fragment resumes program execution, stops at the breakpoint,
 #-- and displays the values of gstopped and newstopped.

 Go onEntry Begin
    Printf "gStopped is %d\n",gStopped
    Printf "newStopped is %d\n",newStopped
 end

 See also    Step, Stop
-
Heap —displays, checks or totals heap information
 Syntax
    Heap [ display ] [ addr ] [  blocktype  ]
    Heap check [ addr ]
    Heap totals [ addr ] [ blocktype ]

 Heap Display Description
    The Heap command displays information about the specified heap. Display is the
 default if you don’t specify any options, so you can omit it if you wish.
 Addr specifies the beginning address of a heap. If you omit this parameter,
 Heap displays information about the heap pointed to by the global variable theZone.
 By default, the following information is displayed:
    •    a dot if the object is locked or nonrelocatable
    •    the address of the beginning of the block and the block length
    •    the block type: H=relocatable, P=nonrelocatable, F=free
    •    the address of the master pointer if it’s a relocatable block
    •    block attributes (Flags): L=locked, R=resource, P=purgeable
    •    for standard toolbox data structures, a description of the structure
    •    for a resource, the resource type and ID, the reference number of the
        file it’s in, and the resource name
    You can specify one of the following blocktypes to limit the display to a
 particular type of block:
    •    purge[able] - limits the display to purgeable blocks.
    •    nonreloc[atable] - limits the display to nonrelocatable blocks.
    •    reloc[atable] - limits the display to relocatable blocks.
    •    free - limits the display to free blocks.
    •    lock[ed] - limits the display to locked  blocks.
    •    res[ource] - limits the display to resources.
    •    restype 'type' - limits the display to the specified resource type.
    Note that the resource type is case-sensitive and you must enclose it in single
 quotation marks ('MENU', for example).

 Example

 #-- Display heap information for 'MENU' type resources.
 Heap restype 'MENU'

 #-- output
 BlkAddr    BlkLength Typ MasterPtr  Flags RType   RId RFRef  RName
 $00316590  $00000098  H  $0031452C    R   MENU   1000 $0584  "File"
 $00316838  $00000050  H  $00314528    R   MENU   1001 $0584  "Edit"
 $00316888  $000000F4  H  $00314524    R   MENU   1002 $0584  "Log"


 Heap Check Description
     The Heap check command checks the consistency of the current application heap,
 which is by default the heap referenced by the global variable theZone. If you
 specify addr -the address of another heap zone- it must be the address of the heap
 zone header (you can’t check part of a heap).
    Heap check performs range checking to make sure all pointers are even and
 non-NIL, and that block sizes are within the range of the heap. It verifies that
 the self-relative handle points to a master pointer referring to the same block. For
 nonrelocatable blocks, it checks if the heap zone pointer points to the zone where
 the block exists. Heap check also verifies that the total amount of free space is
 equal to the amount specified in the header, and that all pointers in the free
 master pointer list are in the heap.

 Examples

 #-- This example intersperses Printf commands with Heap check commands to show at
 #-- which memory locations the heap is okay.
 Printf "Checking %P's heap at $%.08X\n", ^Pstring( $910)^, TheZone
 Heap check TheZone

 Printf "Checking the System heap at $%.08x\n", SysZone
 Heap check SysZone

 Printf "Checking the MultiFinder heap at $%.8x\n", **$2a6+$c
 Heap check $2a6^^+$c

 #-- output
 Checking SADE's heap at $00146EF2
    The heap is okay.
 Checking the System heap at $00001400
    The heap is okay.
 Checking the MultiFinder heap at $00023d64
    The heap is okay.


 Heap Totals Description
     The Heap totals command summarizes the state of the current application heap,
 which is by default the heap referenced by the global variable theZone. You can
 specify another heap that starts at addr, the beginning address of a heap.
    Information is given for free, nonrelocatable, and relocatable objects. If you
 wish to restrict the display to a particular type of block, use the blocktype
 parameter. You can specify one of the following blocktypes to limit the display
 to a particular type of block:
    •    purge[able] - limits the display to purgeable blocks.
    •    nonreloc[atable] - limits the display to nonrelocatable blocks.
    •    reloc[atable] - limits the display to relocatable blocks.
    •    free - limits the display to free blocks.
    •    lock[ed] - limits the display to locked blocks.
    •    res[ource] - limits the display to resources.
    •    restype 'type' - limits the display to the specified resource type.
    Note that type is case-sensitive and you must enclose it in single quotation
 marks ('MENU', for example).

 Example

 Heap totals

 #-- output
                          Total Blks  Total Size
 Free                             23       49080
 Nonrelocatable                    7        1348
 Relocatable                      89       21232
   Locked & NonPurgeable           2        5796
   Locked & Purgeable              2        8136
   UnLocked & Purgeable            6         680
   UnLocked & NonPurgeable        79        6620
 Heap (total)                    119       71660
-
Help —displays help information
 Syntax
     Help [ identifier ,… ]

 Description
     The Help command displays information about using SADE, including the syntax
 of all SADE commands. To see what values identifier can have, just enter Help.
-
If ...End —conditionally executes commands
 Syntax
     If  Boolean  [ then ]
        commands
    [ elseif Boolean   [ then ]
        commands ] ...
    [ else
        commands ]
    End

 Description
     The If...End construct allows for conditional execution of sequences of SADE
 commands. Each If must be concluded by a corresponding End. Although elseif and
 else are optional, they must appear between the If and End in the order indicated
 in the syntax description. You can use more than one elseif but at most one else.
    The commands controlled by an If extend to the corresponding End, or to the
 first corresponding elseif or else. The commands controlled by an elseif extend to the
 next corresponding elseif, else, or end. The commands controlled by an else extend to
 the corresponding End.
    When an If...End construct is evaluated, if the If Boolean is true, the statements
 controlled by the If are executed and the remainder of the construct to the End
 keyword is skipped. If the Boolean is false, the statements controlled by the If
 are skipped and the next (elseif) condition is checked, if present. If an elseif
 condition is evaluated and is true, the commands it controls are executed and the
 remainder of the construct is skipped. If no conditions are evaluated as true, when
 the else command is reached (if present), the commands controlled by the else are
 executed (otherwise, they’re skipped).
    You can nest If...End constructs.

 Example

 #-- Step through a five element array using a low to high index, looking for
 #-- the first true element, and resetting it to false. The first four elements
 #-- are true and the last one is false.

 Define global Test[5] := (4 of 1,0)

 Proc IfDemo
    Define WhichTest
    Define ShowMe
    For WhichTest:= 1 to 5 do
        Printf "\n"
        For ShowMe:= 1 to 5 do
            Printf "%t", test[showMe]
        End
        Printf " - "
        if Test[1]
            "Test[1] true"
        elseif Test[2]
            "Test[2] true"
        elseif Test[3]
            "Test[3] true"
        elseif Test[4]
            "Test[4] true"
        elseif Test[5]
            "Test[5] true"
        else
            "all tests false"
        End
        Test[ShowMe] := 0
    End
 End

 IfDemo

 #-- output

 11110 - test[1] true

 01110 - test[2] true

 00110 - test[3] true

 00010 - test[4] true

 00000 - all tests false

 #-- This example shows a SADE procedure that steps until the menuItem variable
 #-- is false.

 Proc StepWhile
    If menuItem =  1
        Step onEntry StepWhile
    Else
        Stop
    End
 End

 Step onEntry StepWhile
-
Kill —terminates an application
 Syntax
     Kill  [ filename  ]

 Description
     If you want to terminate an application, (whether it’s suspended or not), use the
 Kill command. Be aware, though, that Kill is dangerous, since it doesn't give the
 unlucky application a chance to perform its usual exit routines (like saving data).
 Kill does perform cleanup activities like freeing the MultiFinder memory occupied by
 the application and removing its trap patches.
    Filename specifies the name of the application or tool to terminate. It is a
 string expression and you must enclose it in quotation marks if it’s a string
 constant. The filename parameter is optional; if you omit it, SADE simply terminates
 the current target application.
    If you are debugging an MPW Tool, the MPW Shell, not the tool itself, is SADE’s
 target. Therefore, if you want to kill a tool that is targeted but leave MPW running,
 you cannot use the Kill command. For this purpose, SADE provides a procedure named
 KillTool; that suspends the execution of a tool but leaves MPW running. The KillTool
 procedure is defined in the SADEStartup script, so it is always available. To use the
 procedure, simply execute the command KillTool from the Worksheet window. You can
 also kill a tool but leave MPW running by choosing the Kill menu command from the
 File menu. If a tool is being debugged when the Kill menu item is chosen, SADE
 calls KillTool.

 Examples

 #-- Terminate execution of the current target.
 Kill

 #-- Define a variable, ExPath that specifies the path to the Sample application. Kill
 #-- terminates Sample by using Concat to concatenate the directory path with the
 #-- application name.
 Define ExPath := "Volume1:CExamples:"
 Kill Concat(ExPath, "Sample")
-
Leave —exits from a looping construct
 Syntax
     Leave  [ if  Boolean ]

 Description
     The Leave command lets you exit from a Loop, While, Repeat, or For construct. You
 can specify a condition for leaving with the if parameter. If the expression
 specified by Boolean evaluates to true, then you exit the loop, otherwise continue to
 repeat the commands in the loop.

 Example

 #-- Increment the variable testNum each time through the loop. Exit the loop
 #-- when testNum reaches 3.

 Define testNum := 0
 Repeat
    Printf "testNum = %d\n", TestNum
    Leave if testNum = 3
    testNum := testNum + 1
 Until testNum = 6
 Printf "after leaving Repeat loop - testNum = %d\n", testNum

 #-- output

 testNum = 0
 testNum = 1
 testNum = 2
 testNum = 3

 after leaving Repeat loop - testNum = 3

 See also    Cycle, For, Loop, Repeat, While
-
Length —returns length of a string
 Syntax
     Length ( string )

 Description
     Length returns the length in bytes of the specified string.

 See also    SizeOf
-
List —lists processes, tracepoints, and breakpoints
 Syntax
     List process
        or
    List trace  [ traps | addrs ]
        or
    List break  [ traps | addrs ]

 Description
     The List command shows the active processes, breakpoints, and tracepoints.
    For processes, the display includes the following information: a process
 number, a creator, and the filename for the process.
    For breakpoints and tracepoints, List displays the location along with its
 symbolic representation. The optional traps or addrs keywords limit the
 display to trap or address breakpoints (or tracepoints) respectively.

 Examples

 #-- List the breakpoints that have been set and the active processes.

 List break         # list all breakpoints set

 #-- output
    EVENTLOOP.(5)    <has break action>
    EVENTLOOP.(11)
    EVENTLOOP.(2)

 List Process

 #-- output
 Process#, creator, FileName
       2, 'MACS', 'Finder'
       3, 'MSWD', 'Microsoft Word'
       4, 'sade', 'Sade'
       5, 'MPNT', 'MacPaint'
     s 7, '????', 'Sample1'

 See also    Trace, Break
-
Loop ...End —repeats commands until Leave
 Syntax
     Loop
        commands
     End

 Description
     The Loop...End construct provides unconditional looping. The enclosed commands
 are executed repeatedly. To exit the loop, use the Leave command.
    You can nest Loop constructs.

 Example

 Define Inner := 0
 Define Outer := 0
 Loop
    Loop
        Inner := Inner + 1
        Printf "Inner: %d " , Inner
        Leave if Inner > Outer
    End
    Inner := 0
    Outer := Outer + 1
    printf "Outer: %d\n", Outer
    leave if Outer > 4
 End

 #-- output
 Inner: 1 Outer: 1
 Inner: 1 Inner: 2 Outer: 2
 Inner: 1 Inner: 2 Inner: 3 Outer: 3
 Inner: 1 Inner: 2 Inner: 3 Inner: 4 Outer: 4
 Inner: 1 Inner: 2 Inner: 3 Inner: 4 Inner: 5 Outer: 5

 See also    Leave
-
Macro —defines a macro
 Syntax
     Macro name  string-expr

 Description
     The Macro command associates a string of characters with a name. Macros allow you
 to define short, familiar names to use instead of long, unfamiliar strings. For
 instance, the SADEStartup file defines macros that let you use MacsBug-like syntax
 for certain SADE commands.
    String-expr    specifies the string of characters to associate with the macro. You
 must enclose it in quotation marks. If you specify a string constant (such as a
 directory name) you must enclose it in two sets of quotation marks.
    Macro definitions can be nested; that is, they can contain references to other
 macros. Macro definitions cannot be recursive, however; in other words, a macro
 definition can’t reference itself. Macro definitions are not allowed in structured
 statements. Macros may be redefined. Macro definitions are limited to a length of 254
 characters.

 Examples

 Macro br 'break'
 Macro clr  'Unbreak all'

 Macro dir "'volume:very:long:directory:path'"
 directory dir
-
MoveWindow —moves window to location
 Syntax
     MoveWindow  [ to h,v ] [window  ]

 Description
     Moves the upper-left corner of the specified window to the specified location.
 The coordinates (0,0) are located at the left side of the screen at the bottom of the
 menu bar. If the location specified would place the window’s title bar entirely off
 the visible screen, an error is returned. If you do not specify a window SADE
 assumes the target window (the second window from the front). If you do not specify
 a location, SADE returns the window’s location without any effect on the window.
    The keyword To is followed by the horizontal and vertical coordinates (in
 pixels) of the new location in that order. They are nonnegative integers. Separate
 them by a comma.

 Examples

 #-- Move the target window’s upper-left corner to a point approximately one inch
 #-- in from the upper-left corner of the screen, and one inch below the bottom of
 #-- the menu bar. (There are about 72 pixels per inch on the Macintosh display
 #-- screen.)

 MoveWindow to 72, 72

 #-- The next example returns the location of the target window, which would be
 #-- 72, 72 when executed after the command in the first example.

 MoveWindow

 # output-
 # MOVEWINDOW 72 72

 See also    SizeWindow, WindowSize
-
NaN —not a number
 Syntax
     NaN ( expression )

 Description
     NaN converts the specified expression into a SANE 10-byte extended value.
-
OnEntry —sets commands for SADE entry
 Syntax
     OnEntry [ exception-action ]

 Description
     The OnEntry command supplies commands that are to be executed each time SADE is
 entered. Each OnEntry command replaces the commands specified by the previous
 OnEntry command. In the SADEStartup file, the StandardEntry procedure is specified
 as an OnEntry exception action. You can define your own OnEntry actions in the
 SADEUserStartup file, but you’ll probably want to use the one in SADEStartup
 as a model (so as not to lose the operations it performs).
    Because the OnEntry command accepts only one command or procedure invocation, if
 you want to execute multiple commands and/or procedures upon entry, use the
 Begin..End construct to group them.

 See also    Break, Begin
-
Open —opens a file
 Syntax
     Open [ source ]  [ behind ]  filename

 Description
     The Open command opens the specified file. Specifying source opens the file as
 read-only. If this option is omitted, the window is opened as a read-write window.
 Specifying behind opens the window behind the front most SADE window; otherwise,
 it’s opened as the front most window.
    If the file is in the current directory, you can specify the name only; otherwise,
 specify a complete or partial directory name as well as the filename. The file must
 be of type 'TEXT' or SADE will be unable to open it. Filename is a string expression
 and must be enclosed in quotation marks if it’s a string constant.

 Example

 Open source 'myFile'

 See also    Close, Save
-
Printf —prints formatted output
 Syntax
     Printf  [ format [ , argument ] … ]
        or
    Printf  [ ( format [ , argument ] … ) ]

 Description
     The Printf command prints string characters to a SADE window or file. You can
 also use Printf to convert values—for example, convert decimal characters to
 hexadecimal—and to specify how the output appears. Format is a string containing
 characters to print, as well as format specifications for arguments that follow.
 Format specifications are preceded by the % character. For instance, to print
 the value of the variable myVar as a decimal number along with a message (assuming
 its value is 5), enter:

    Printf "The value of myVar is %d", myVar

 #-- output
 The value of myVar is 5

    Remember that the format specification is a string so you must enclose it,
 including the percent sign, in quotation marks.
    Argument is the value to be printed; it can be an actual numeric value or a
 variable whose value you want to print. Each format specification applies to zero
 or more arguments. When the format specifications are exhausted, any remaining
 arguments are ignored. Likewise, when the specified arguments are exhausted, any
 remaining format specifications are ignored.

 Examples

 #-- Displays record definition of system type EventRecord.
 #-- Notice how EventRecord.Where, which is of type Point, has been
 #-- expanded to show its definition too.

 Printf "%P", ^pstring($910)^
 myProg

 Printf "%P", *(pstring*) $910
 myProg

 Printf "%-t", EventRecord
 RECORD
   WHAT: Word;
   MESSAGE: Long;
   WHEN: Long;
   WHERE: RECORD
            CASE Word OF
              (1):
                (RECORD
                   V: Word;
                   H: Word;
                 END);

              (2):
                (RECORD
                   VH: ARRAY [(0, 1)] OF
                         Word;
                 END);
          END;
   MODIFIERS: Word;
 END

 #-- Doing the same thing with a target program variable
 #-- of type EventRecord. The %t format specifier lets
 #-- the Printf display format be controlled by the
 #-- type of the variable displayed.

 typeof(myEvent)
   EVENTRECORD

 Printf "%t", myEvent
 RECORD
   WHAT: 3;
   MESSAGE: 16686;
   WHEN: 284053;
   WHERE: RECORD
            CASE Word OF
              (1):
                (RECORD
                   V: 272;
                   H: 267;
                 END)
              (- - -);
          END;
   MODIFIERS: 2432;
 END
-
Proc ...End —defines a SADE procedure
 Syntax
     Proc  name [ argName ,... ]
        commands
    End
        or
    Proc  name  [ ( argName ,... ) ]
        commands
    End

 Description
     SADE procedures are delimited by the Proc...End construct. The procedure name
 is followed by an optional parameter list; if present, the list identifies parameters
 by name only. Parameters are not assigned a type but instead take on the types of the
 actual parameter values when the procedure is called. You can enclose the parameter
 list in parentheses if you wish, but if you do so, you must also use parentheses
 when calling the procedure (and vice versa).
    When you call a procedure, the number of actual parameters that you pass
 need not match the number of formal parameters in the procedure definition. If you
 pass fewer parameters than the number of formal parameters, SADE assigns a special
 undefined value to the formal parameters for which there are no corresponding actual
 parameters.
    If you pass more actual parameters than there are formal parameters, SADE ignores
 the extra parameters unless you use the predefined SADE variables Arg and Nargs in
 your procedure definition. Arg is an array variable that has the form Arg[n]
 where n is the nth actual parameter passed when the procedure is called. Nargs
 contains the number of actual parameters. These two predefined variables enable you
 to write flexible procedures when you don’t know how many parameters will actually be
 passed when the procedure is called. Two of the examples show a simple for loop that
 uses Arg and Nargs to set multiple break points. Note that the values of these
 variables represent the parameter state of the currently active procedure and are not
 defined outside of it.
    You must define a procedure before making a call to it. Therefore, if you want
 mutually recursive procedures, you must first define a “dummy” procedure (similar
 to a Pascal FORWARD definition). You can then write a second procedure that calls
 the dummy procedure, and then redefine the dummy procedure to do what you want
 (including calling the second procedure). The minimal dummy procedure definition is:
 Proc foo; End;.
    You can nest procedure calls.

 Examples

 #-- This example illustrates the use of the Nargs and Arg variables to write a
 #-- procedure that will accept an indefinite number of parameters. When you call
 #-- this procedure, it sets a breakpoint on each parameter that you pass. Nargs
 #-- contains the number of the last parameter passed; Arg is used like an array
 #-- variable to accesses each parameter by number. Therefore, the loop is in effect
 #-- for the first through the last parameter passed, and each parameter is passed
 #-- in turn to the Break command by way of the count and arg variables.

 Proc SetBreaks ()
    Define count
    For count := 1 to Nargs
        Break Arg[count]
    End
 End

 #-- Call SetBreaks to set breakpoints on DrawWindow, EventLoop, SetLight

 SetBreaks (DrawWindow, EventLoop, SetLight)

 See also    Func
-
Quit —quits SADE
 Syntax
     Quit

 Description
     The Quit command terminates SADE and passes control to another process as
 determined by MultiFinder. Be aware that Quit kills any suspended applications.

 See also    Shutdown
-
Redirect —redirects output
 Syntax
     Redirect  [ append ]  filename
        or
    Redirect  [ pop ] [ all ]

 Description
     The Redirect command redirects the output from SADE commands to the specified
 file. The append parameter instructs SADE to append output to the end of the
 specified file rather than replacing the contents of the file. You can also use the
 § character (Option-6) to replace or append to the selection in an open window
 see the example below).
    You can nest Redirect commands to as many as 10 different files; SADE maintains
 the names of these files as a last-in, first-out queue. If you use the pop keyword,
 or if you use no parameters at all, the output from SADE commands is redirected to
 the file at the head of the queue. If you specify all or pop all, standard output
 is redirected to the current command window.
    Warning: Be aware that if you use use Redirect to replace the contents of a
 file that’s not open, there’s no way to undo it. (If the file is open, you can
 close it and respond “No” when the dialog asks whether to save changes.)
    Note: Any error conditions cause SADE to perform an implicit pop all for any
 redirected files; this ensures that output returns to the current command window.

 Examples

 #-- Redirects output to the current selection in the file whyNot.

 Redirect "whyNot.§"

 #-- Create a file to hold output from SADE. Entering a string echoes the string.
 #-- That output is redirected to the file, becoming the file's contents. Here the
 #-- string is a comment and a SADE command to execute the contents of the next
 #-- file in the chain.

 Open 'exec1'
 Redirect 'exec1'
    '"\n executing exec1 now"'
    "Execute 'exec2'"

    Open "exec2"
    Redirect 'exec2'
        "'Now executing exec2'"
        "Execute 'exec3'"

        Open "exec3"
        Redirect 'exec3'
            '"Done in exec3"'

 Redirect pop all
 Execute "exec1"

 Alert "Try a tile windows here\n∂
    Then look at the worksheet for output"

 #-- output

 Executing exec1 now
 Now executing exec2
 Done in exec3
-
Repeat ...Until —conditionally repeats commands
 Syntax
     Repeat
        commands
    Until Boolean

 Description
     The Repeat...Until construct provides conditional looping with a test at the end
 of the loop. The enclosed commands are executed until Boolean is true. The enclosed
 commands are executed at least once.
    Repeat constructs may be nested.

 Example

 Define count := 0
 Repeat
    Printf "%d\n", count
    count := count + 1
 Until count = 5

 #-- output

 0
 1
 2
 3
 4

 See also    Leave
-
Request —displays request dialog box
 Syntax
     Request ( string [, string ] )

 Description
     Request returns a string after displaying a request dialog box. The dialog
 presents an OK button and a Cancel button. The first string argument appears in the
 dialog box as the request message. The second, optional string argument specifies a
 default string to present in the request box.
    When you click Cancel, Request returns the string "_CANCEL_" . Otherwise, it
 returns the string that you enter in the box.

 Example

 Request('Choose a name','Homer')

 See also    Confirm
-
Resource —displays the resource map
 Syntax
     Resource [ display ] [ addr ] [ restype 'type ' ]
        or
    Resource check [ addr ]

 Description
     The Resource command displays the contents of your application’s resource maps
 and the system resource map. If you want to display only a particular map, addr
 should be the address of the map. The information displayed for each map
 includes:  its location, the resource ID, the resource type, the value of the master
 pointer, whether the resource is locked or unlocked, and the resource name. If a
 resource isn’t loaded, the master pointer field shows “NotLoaded.” The default, if
 you don’t specify any options, is to display the resource maps, so you can omit
 the display option if you wish.
    You can also restrict the display to a particular resource type by using the
 restype keyword with the desired type. Note that type is case-sensitive and should
 be enclosed in single quotation marks ('WIND', for example).
     The Resource check command checks the target application’s resource maps for
 consistency. If you want to check a particular map, addr should point to the
 address of the map. If an inconsistency is found, the command displays a diagnostic
 message specifying the problem.

 Example

 Resource restype 'MENU'

 #-- output

 Resource Map at $00501E8C
   ResId  RType  MasterPtr  Locked?   Name
     128  MENU   $00501E8C  Unlocked
     129  MENU   $00501EC0  Unlocked
     130  MENU   $00501F50  Unlocked
     131  MENU   $00501FA0  Unlocked
 Resource Map at $0010CF68
   ResId  RType  MasterPtr  Locked?   Name
   33024  MENU   NotLoaded
   49046  MENU   $0010EC94  Unlocked
   49047  MENU   $001683F8  Unlocked
   49063  MENU   $000DF76C  Unlocked
   49064  MENU   $0010E764  Unlocked
   49065  MENU   $0010E794  Unlocked
   61536  MENU   NotLoaded
-
Return —returns from a procedure or function
 Syntax
     Return [ result ]

 Description
     The Return command returns you from a procedure or function currently in execution.
 When returning from a function, the function result must be specified. (When
 returning from a procedure, there is no return value.)
    Result is an expression that specifies the return value.

 Example

 Define global SadeArray[4] := (1, "this is two", 3.3, 4)
 Func MiscTypes (index)
    Return SadeArray[index]
 End

 Define selector
 For selector := 1 to 4 do
    Printf "%t \n", MiscTypes(selector)
 End

 #-- output

 1
 this is two
 3.3
 4

 See also    Func, Proc
-
SADEKey —defines a key for entering SADE
 Syntax
     Sadekey [ keycode ]

 Description
     The SADEKey command lets you specify a different Command-Option key combination
 for entering SADE. To see what key is specified as the SADEKey, just type SADEKey.
 A complete list of keycodes can be found in the Toolbox Event Manager chapter of
 Inside Macintosh Volume V.

 Example

 sadekey $33    #-- define Command-Option-Delete combination as SADEKey
-
Save —saves a file
 Syntax
     Save [ all | filename ]

 Description
     The Save command saves the specified file or, if all is specified, saves all
 files. If the specified file wasn’t modified since the last time it was saved,
 Save does nothing. If no parameters are given, Save saves the target window. Filename
 is a string expression and you must enclose it in quotation marks if it’s a string
 constant.

 Example

 Save 'myFile'

 See also    Open, Close
-
Selection —returns text of current selection
 Syntax    Selection ( windowName )

 Description
     Selection returns the text of the current selection in the specified window.
 The value returned is of type PString. To get the value of the string if it contains
 a name or expression (for instance, to set a breakpoint), apply the Eval function
 on the string.

 Example

 #-- Return the string that is highlighted in the active window, that is, the
 #-- frontmost window.

    Selection (ActiveWindow)

 See also    Eval
-
Shutdown —shuts down or restarts the machine
 Syntax
     Shutdown [ restart ]

 Description
     The Shutdown command terminates SADE and calls the Shutdown Manager. Be aware
 that all unsaved work is lost. Specifying restart will restart the Macintosh after
 shutting down.
-
SizeOf —returns size of variable, type, or argument
 Syntax
     SizeOf ( variable | type | argument )

 Description
     SizeOf returns the number of bytes occupied by a variable or type. You can also
 use SizeOf to determine the size of an argument to a SADE procedure or function.
 You cannot use SizeOf with SADE array variables.

 Example

 #-- This example shows the size of the SADE type, Long.

 SizeOf(long)

 #-- output

 4

 See also    Length
-
SizeWindow —sets a window’s size
 Syntax
     SizeWindow [ to h,v ] [window ]

 Description
     SizeWindow sets the size of the specified window to the specified horizontal
 and vertical dimensions. If the size specified would cause the window to be too big
 for the screen, SADE returns an error message. Window is the name of the window
 to size. If you do not specify a window, SADE uses the target window (second
 from the front).
    The keyword To is followed by the horizontal and vertical dimensions (in
 pixels) of the window in that order. They are nonnegative integers. Separate
 them by a comma.

 Examples

 #-- Make the target window 200 pixels square in size. Note that a there are
 #-- about 72 pixels per inch on the Macintosh display screen.

 SizeWindow To 200, 200

 #-- Display the size of the sample.c window:

 SizeWindow 'sample.c'

 #-- output

 SIZEWINDOW 630 393 sample.c

 #-- Make the Worksheet window 500 x 100 pixels in size. Note the use of
 #-- the built-in Concat function to concatenate the directory path defined
 #-- by sadedir with the name of the SADE Worksheet.

 SizeWindow To 500, 100 Concat(sadedir,'SADE Worksheet')

 See also    MoveWindow, WindowSize
-
SourcePath —tells SADE where your source files are
 Syntax
     Sourcepath [ [ add | del[ete ] ] directoryName , ... ]

 Description
     The SourcePath command tells SADE what directory your source files are in. If
 your source files are in more than one directory, you can give the SourcePath
 command a list. The a list of directory names must be separated by commas.
     If you’re unsure which directories you’ve specified, simply enter
 Sourcepath and the current search path is displayed.
     Specifying the add parameter will add a directory to the list of directories
 in the search path. Specifying del[ete] deletes a directory from the list of
 directories in the search path.

    Warning: If you specify a directory without using the add keyword, any
 directories previously specified are replaced.

 Examples

 Sourcepath 'srcdir', ':otherdir'  # sources in more than one directory

 Sourcepath add ":samples"         # add directory Samples to search path

 See also    Directory
-
SourceToAddr —returns address of source statement
 Syntax
     SourceToAddr ( windowName [, errorFlag ] )

 Description
     SourceToAddr returns the address corresponding to the statement selected in the
 specified window. The window need not be active. SourceToAddr displays the address
 symbolically; SourceToAddr returns zero if it cannot determine the address. If you
 pass a nonzero value in the optional errorFlag, SourceToAddr returns a string
 describing why the address could not be found.

 Example

 #-- SourceToAddr returns the address of the statement that a user has highlighted
 #-- in the target (source code) window. If the user has highlighted code that
 #-- does not represent a statement, that is, if SourceToAddr returns a Pstring,
 #-- then SADE returns an error to the user. Note that this code is similar to code
 #-- in the SADEStartup file that implements the Statement Selected Is? item in the
 #-- SourceCmds menu.

 foo := SourceToAddr(targetWindow,1)
 If TypeOf(foo) = 'PString' then
    #report error in foo
 else
    #foo has address

 See also    AddrToSource
-
Stack —displays stack frames
 Syntax
     Stack  [ count ] [ at addr ]

 Description
     The Stack command displays a list of the stack frames for the target application.
 The stack frames displayed are based on register A6 or addr if at is specified.
 For each entry, Stack gives the address of the stack frame, the name of the
 procedure or function that allocated the frame, and the name and offset (if
 available) of the parent procedure.
    The count parameter is the maximum number of stack frames to display counting
 back from the current frame).

 Example

 Stack at DisplayText.(6)
 Stack
  Frame Addr  Frame Owner   Called From
    <main>      %__MAIN
    $0032BC24   main          %__MAIN+$0028
    $0032BB2C   SkelMain      main.(51)
    $0032BB0C   LogEvent      SkelMain.(13)+$0012
    $0032BADC   ReportUpdate  LogEvent.(50)+$0004
    $0032BACC   DisplayText   ReportUpdate.(1)+$0004
-
Step —executes single step
 Syntax
     Step [ asm | line ] [ into ] [ onEntry commands ]

 Description
     The Step command lets you execute your program one step at a time, from either
 the source code level or the object code level.
    Specify line to perform source-level debugging. This is the default, so you can
 omit this option if you wish. Specify into to step into subroutines. The default,
 if you omit this parameter, is to step over subroutines.
    Specify asm to perform object-code (assembly-language) debugging. The default,
 if you omit this parameter, is source-level debugging. If you specify asm, execution
 proceeds one instruction at a time; the instruction at the program counter is
 executed and SADE is re-entered. SADE always treats traps as single instructions;
 SADE steps over them, stopping at the first instruction following the trap. You can
 either step into or over subroutines called by JSR and BSR instructions. If you
 specify into, SADE steps in, stopping at the first instruction of the subroutine.
 If you omit into, SADE treats BSR (branch to subroutine) and JSR (jump to subroutine)
 instructions as single instructions.
    The onEntry commands option is used to specify actions to occur upon returning
 to SADE after stepping the program—for example, to display the value of a variable.
 This option is required if you want to execute more than one step at a time as part
 of a script or SADE procedure. If you do not use onEntry but execute the Step command
 as part of a group of commands (in a script file or highlighted in the Worksheet)
 SADE evaluates the other commands first before executing the Step command regardless
 of the order in which you place the commands in the script or in the Worksheet.
 This means, for example, if you place a command such as Printf after a Step command
 to display the value of a variable, and execute the commands together, Printf
 displays the value of the variable before, not after, the step.

    Important: You cannot execute more than one Step command at a time, whether as
 part of a script or as a highlighted group of commands unless you use the onEntry
 keyword. With onEntry you can tell SADE to execute another Step command after
 returning to SADE following the first step.

    Warning: Don’t try to step over a routine that does not return to the caller; for
 instance, a call to longjmp(). SADE steps over procedure and function calls by
 setting the trace bit until after the JSR or BSR is executed, and then replaces the
 return address with the address of a SADE routine. Since longjmp() restores a
 previously saved register set, including a new stack pointer, SADE’s return is lost.
 If you want to go to the routine restored by longjump0, execute Step asm into until
 the registers have been modified and then do a source step. Or better still, if you
 know where the jump will go, set a breakpoint in that routine.

 Examples

 #-- If these two commands are executed together, SADE displays the value of
 #-- newStopped before stepping the program (remember that SADE evaluates all
 #-- other commands in a script before executing a Step command).

 Step
 Printf "The value of newStopped is %d",newStopped

 #-- output - value of newStopped before step

 #-- Use the onEntry keyword to display the value of a variable after stepping.
 #-- Note in the second example that the Printf command is part of the Step command—it
 #-- belongs to the action specified by onEntry—so it must be on the same line as Step
 #-- or, as in this case, made part of the line by the continuation character (∂).

 Step onEntry ∂
    Printf "The value of newStopped is %d",newStopped

 #-- output - value of newStopped after step

 #-- You can use the Begin..End construct to execute multiple commands as part of the
 #-- action specified by onEntry. This example displays the value of three different
 #-- variables after stepping.

 Step onEntry Begin
    Printf "The value of newStopped is %d\n",newStopped
    Printf "The value of gStopped is %d\n",gStopped
    Printf "The value of menuID is %d\n",menuID
 End

 #-- To step through a program using a script or a block of SADE commands, you
 #-- must use the onEntry command. The following procedure uses onEntry to step
 #-- a given number of times (in this case three times); the onEntry command tells
 #-- SADE what to do after each step. In this case, onEntry instructs SADE to
 #-- take another step.

 define StepCount
 proc __Step__
    if (StepCount > 0)
        StepCount := StepCount - 1;
        step OnEntry __step__
    end
 end
 proc StepN(__n__)
    StepCount := __n__
    Step OnEntry __Step__
 end

 StepN (3)    # Step three times

-
Stop —terminate break action
 Syntax
     Stop

 Description
     The Stop command terminates the current break action and returns you to SADE.
 If the current execution was within a structured statement (Begin...End, for
 instance), or if multiple commands were selected, the pending commands are executed.
 To terminate a break action and cancel pending commands, use the Abort command.

 Example

 Directory  'VolName:Path:toMyProg:'
 Target 'myProg'

 Proc WhichEvent(stopType)
    Define global EventType[16] := ('null',
    'mouse-down','mouse-up',
    'key-down', 'key-up','auto-key',
    'update', 'disk-inserted','activate',
    'network', 'device driver', 'app1',' app2', 'app3', 'app4')

    If theEvent.what  = stopType then
        Printf "%P received, stopping\n", EventType[stopType+1]
        Stop
    else
        EventType[theEvent.what+1]
        Printf
    End
 End

 Break _waitNextEvent from applzone..applzone^ whichEvent(1)
 Go

 #-- output

 key-down
 update
 key-down
 mouse-down received, stopping

 See also    Abort, Break, Quit
-
Target —identify your application
 Syntax
     Target [ progName [ using symbolFileName ] [ onEntry commands ] ]

 Description
     The Target command tells SADE the name of the application you want to debug and
 identifies the symbol file (the .SYM file generated by the linker). Target also
 launches the application, stopping at the first line of the main program, and opens
 the source file containing main. To find out what the current target is, just type
 Target. To release the current target application (for example, if an application is
 targeted by SADE, you cannot relink it until you release it) use Target with a null
 string enclosed by double quotation marks, that is, Target "".
    progName is the name of the application to debug. Enclose it in quotation
 marks if it is a string constant. If you omit progName, SADE returns the name of the
 current target application.
     SymbolFileName is the name of the symbol file generated by the linker. Enclose it
 in quotation marks if it is a string constant. If the .SYM file is already in the
 same directory as the application and is called progName.SYM (which it usually is),
 you don't need to bother with the using option.
    The onEntry option is used to specify actions to occur upon returning to SADE
 after launching the program.
    Note: If you select the Stop Before Constructor menu command, SADE stops
 your program as soon as it is launched instead of bringing it to the first line
 of main.

 Examples

 #-- The first example specifies the MPW Shell as the target and uses the using
 #-- option to specify ToolStuff as the tool to debug. Note that the Target command
 #-- automatically opens the source file and breaks at main.(0).

 SourcePath add "VolName:MPW:ToolStuff:"
 Target "VolName:MPW:MPW Shell" using "VolName:MPW:ToolStuff:tool.sym"
 #-- Run tool to break to SADE with tool as target.
 #-- Target puts pc at main.(0) automatically

 #-- The Target command in this example puts a breakpoint in the DoMenuCommand
 #-- routine and runs the program to that point.

 Target 'sample1' onEntry Begin
    break DoMenuCommand
    Go
 End
-
Timer —returns timing values
 Syntax
     Timer ( [ value [, Boolean ]])

 Description
     Timer uses the global variable TickCount to provide timing-related functions.
 If you pass no arguments, Timer returns the current TickCount. If you specify a value
 (typically a previous value of TickCount), Timer returns the difference between
 that value and the current value of TickCount (that is, TickCount–value). If you
 also specify a nonzero Boolean value, the difference is returned as a string of the
 form "sss.hh", representing seconds and hundredths of a second. (If the Boolean
 is zero, it’s ignored.)

 Example

 #-- Execute together the lines in the following example to see how long SADE
 #-- takes to launch your application.

 Define starttime := Timer()
 Target 'sample1' onentry Timer (starttime,1)
-
Trace —sets tracepoints
 Syntax
     Trace addr ,…
        or
    Trace trap [ from  addrRange ] ,...
        or
    Trace trap-range [ from  addrRange ] ,...
        or
    Trace all traps [ from  addrRange ]

 Description
     The Trace command sets tracepoints on the specified address or traps within the
 target program. You can set tracepoints on a single trap, a range of traps, or on
 all traps. After setting the tracepoints, you can resume program execution. When the
 program encounters the tracepoint, SADE displays a message on standard output,
 reporting the address or trap being traced, with a symbolic representation of the
 address if possible. Program execution resumes after SADE displays the message.
     Addr is a RAM address or symbolic reference. If you use a symbolic reference,
 the code need not be in memory at the time you set the tracepoint.
     Trap is a trap name or number. You must prefix a trap number with the trap
 character (†—Option-t) and a trap name with an underscore character (_InitGraf, for
 example).
    Trap-range specifies a range of traps. Use the range operator (..) between trap
 names or numbers.
     If addrRange is specified, SADE displays the trace message only when the trap is
 called from the specified range.
    Specifying all traps sets a tracepoint on every trap.
    You can specify multiple tracepoints, separated by commas, with a single Trace
command.
    To remove a tracepoint, use the Untrace command.

 Example

 #-- These two Trace commands set traces on a range of traps, in the first case
 #-- using trap names with the underscore character, and in the second case using
 #-- the trap operator with trap numbers.

 Trace _OpenResFile.._GetResource
 Trace †$A997..†$A9A0

 See also    Break, List, Untrace
-
TypeOf —return type of an expression
 Syntax
     TypeOf ( expression )

 Description
     TypeOf returns a string containing the name of the type of the given expression.
 If SADE doesn’t know the name of the type, it returns a string of the form
 "Type  #n ", where n is SADE’s internal index for the type.
-
Unbreak —removes breakpoints
 Syntax
     Unbreak addr ,...
        or
    Unbreak trap ,...
        or
    Unbreak trap-range ,...
        or
    Unbreak all  [ traps | addrs ]

 Description
     The Unbreak command clears the breakpoint as well as any associated break action,
 for the specified addresses or traps. The all option clears all breaks set in the
 target program. The all option can also be followed by traps or addrs to restrict
 the command to traps or addresses respectively.
    Addr is a RAM address or symbolic reference. Trap is a trap name or number. You
 must prefix a trap number with the trap character (†—Option-t) and a trap name with
 an underscore character (_InitGraf, for example). Use the range operator (..) between
 trap names or numbers to remove breaks set on a range of traps.

 Example

 Unbreak _GetResource    #undo break on GetResource trap

 See also    Break
-
Undef —determines if variable is undefined
 Syntax
     Undef ( parameter | variable )

 Description
     Undef determines whether the given SADE parameter or variable has been
 initialized. If the parameter or variable is initialized, Undef returns 0; if it’s
 not initialized, Undef returns 1. If you pass an undefined identifier to Undef,
 an error results.
-
Undefine —removes definitions
 Syntax
     Undefine name ,...

 Description
     The Undefine command removes the definition of the specified global SADE variable,
 procedure, function, or macro. You can supply a list of names to remove multiple
 definitions. Note that Undefine does not remove local variables defined within SADE
 procedures or functions.
    If you want to redefine an item, you don’t need to use Undefine; you can just
 assign a new value to the existing name using the Define command.

 Example

 Proc ControlledProc
    Printf "%d   ", ControllerGlobal
 End

 Proc Controller
    Define global ControllerGlobal
    Define max := 7

    For ControllerGlobal := 1 to max
        ControlledProc
    End

    Undefine ControllerGlobal
    Undefine ControlledProc
 End

 #-- output

 Controller
 2   3   4   5   6   7

 ControllerGlobal
 ### Could not find "ControllerGlobal" as a program symbol

 ControlledProc
 ### Could not find "ControlledProc" as a program symbol

 See also    Proc, Func, Macro, Define
-
Untrace —removes tracepoints
 Syntax
     Untrace addr ,…
        or
    Untrace trap ,...
        or
    Untrace trap-range ,...
        or
    Untrace all  [ traps | addrs ]

 Description
     The Untrace command clears the tracepoint at the specified addresses or traps.
 The all keyword clears all tracepoints within the target program. The all keyword
 can optionally be followed by the traps or addrs keywords to restrict the command to
traps or addresses respectively.
    Addr is a RAM address or symbolic reference. Trap is a trap name or number.
 You must prefix a trap number with the trap character (†—Option-t) and a trap name
 with an underscore character (_InitGraf, for example).
    Specify trap-range to remove traces on a range of traps. Use the range
 operator (..) between trap names or numbers.

 Example

 Untrace _GetResource    #undo trace on _GetResource trap

 See also    Trace
-
Version —displays SADE version information
 Syntax
     Version

 Description
     The Version command displays the current SADE version number.
-
Where —returns symbolic representation of address
 Syntax
     Where ( address )

 Description
     Where returns a string containing a symbolic representation of the given address.

 Example

 #-- Return the source statement corresponding to the program counter (pc).
 Where(pc)

 #-- output
 DoMenuCommand.(31)

 See also    AddrToSource
-
While ...End —conditionally repeats commands
 Syntax
     While  Boolean [ do ]
        commands
    End

 Description
     The While...End construct provides conditional looping with a test at the
 beginning of the loop. The enclosed commands are executed as long as Boolean is true.
 If the condition is false at the outset, the enclosed commands are never executed.
    The do option is not required. It is provided only for consistency with Pascal
 usage. As long as the Boolean expression is true, the commands will be executed
 whether you specify this option or not.
    While constructs may be nested.

 Example

 Define goSmall := 10
 While goSmall > -2 do
    While goSmall > 4 do
        While goSmall > 7 do
            Printf "          Inner loop - goSmall = %d\n", goSmall
            goSmall := goSmall -1
        End
        Printf "     Middle loop - goSmall = %d\n", goSmall
        goSmall := goSmall - 1
    End
    Printf "Outer loop - goSmall = %d\n", goSmall
    goSmall := goSmall - 1
 End

 #-- output

           Inner loop - goSmall = 10
           Inner loop - goSmall = 9
           Inner loop - goSmall = 8
      Middle loop - goSmall = 7
      Middle loop - goSmall = 6
      Middle loop - goSmall = 5
 Outer loop - goSmall = 4
 Outer loop - goSmall = 3
 Outer loop - goSmall = 2
 Outer loop - goSmall = 1
 Outer loop - goSmall = 0
 Outer loop - goSmall = -1

 See also    Leave
-
WindowSize —set size of zoom and new windows
 Syntax
     WindowSize zoom | new [ top, left, bottom, right ]

 Description
     The WindowSize command allows you to set the size and position that all newly
 created windows will take, and to set the size and position a window will take when
 you click the Zoom box (upper right corner of the window). Specify the location for
 the four corners of the window (in pixels), in the order: top, left, bottom, right.
    If you specify new, the coordinates that you specify determine the size and
 location of newly created windows in SADE. If you specify zoom, the coordinates
 that you specify determine the size and location of windows in SADE when you press
 the Zoom box. There is no default; you must specify either zoom or new.

 Example

 #-- Specify that new windows will be approximately one inch from the top and one
 #-- inch from the bottom, and will be about two inches long and three inches
 #-- wide. (There are approximately 72 pixels per inch on the Macintosh screen.)

 Windowsize new 72,72,144,216

 See also    MoveWindow, SizeWindow